GitHub-only Project Management Process (Scrum, Multi-repo, Independent Services)

This is an end-to-end GitHub-only workflow to manage development using Scrum across multiple repositories, where each service releases independently.

Your team setup (as provided):

• Repos: gateway, accelerator, ai-case-completion
• Sprint length: 2 weeks
• Done means released (not just merged)
• Example features:
  • gateway: Questionnaire module
  • accelerator: Waterfall chart

---

0) Principles (What makes GitHub-only work)

• One planning surface: a single Org-level GitHub Project (v2) is the Scrum board + backlog for all repos.
• Work lives with code: issues are created in the repo where implementation happens.
• PRs link to issues: every PR references an issue; decisions stay discoverable.
• Done = Released: the team only marks an item Done when it’s shipped (or otherwise released per your definition).
• Automate the boring parts: keep the project board accurate via automation.

---

1) GitHub Components (and how you will use them)

1.1 Organization-level GitHub Project (v2)

Use one Org Project (example name: Delivery Board) as the system of record for:

• Backlog
• Sprint planning
• Sprint execution tracking
• Reporting (per sprint, per repo/service)

Recommended Project fields

• Status (single select):
  • Backlog
  • Ready
  • In Progress
  • In Review
  • Blocked
  • Ready to Release
  • Done (Released)
• Iteration (built-in): 2-week sprints
• Priority (single select): P0, P1, P2
• Estimate (number): story points
• Repo (single select): gateway, accelerator, ai-case-completion
• (Optional) Type (single select): Feature, Bug, Chore, Epic

Recommended views

• Current Sprint Board: Iteration = @current (board grouped by Status)
• Sprint Planning: Iteration = @current AND Status IN (Backlog, Ready)
• Backlog: Status IN (Backlog, Ready) sorted by Priority
• Release Queue: Status = Ready to Release (table by Repo)
• Per-repo views:
  • Repo = gateway
  • Repo = accelerator
  • Repo = ai-case-completion

---

1.2 Repositories

• gateway: gateway-related features and releases
• accelerator: accelerator-related features and releases
• ai-case-completion: AI case completion service-related work and releases

Each repo contains:

• Issues (work items)
• PRs (implementation)
• Releases (tags + GitHub Releases)

---

2) Work Item Types

2.1 Story / Feature (default)

Create a GitHub Issue with:

• Problem / user value
• Acceptance criteria
• Non-goals
• Dependencies
• Rollout notes (flags, migration, backward compatibility)

2.2 Bug / Chore

Same structure, but with:

• Reproduction steps (bug)
• Definition of success (chore)

2.3 Epic / Cross-repo initiative (optional)

Use a Tracking Issue with a checklist of linked Issues across repos.

---

3) Standard Workflow (Status Definitions)

Because Done = Released for your team, it helps to explicitly separate “merged” from “released”.

• Backlog: not ready for sprint commitment; still needs refinement.
• Ready: meets Definition of Ready; can be pulled into a sprint.
• In Progress: actively being implemented.
• In Review: PR open and under review/CI.
• Blocked: cannot proceed due to dependency/risk; must be called out in daily standup.
• Ready to Release: merged + verified + release is the remaining step.
• Done (Released): released (tagged + deployed/available) and acceptance criteria met.

---

4) Scrum Rituals in GitHub

4.1 Backlog Refinement (during sprint)

Where: Org Project + repo issues
Output: issues moved to Ready, sized, clarified.

Definition of Ready (recommended)

• Acceptance criteria written and testable
• Dependencies identified and linked
• Estimate added
• Repo set (gateway, accelerator, or ai-case-completion)
• Priority set

---

4.2 Sprint Planning (every 2 weeks)

Where: Org Project “Sprint Planning” view

Steps:

1. Filter to Status = Ready.
2. Select the sprint items.
3. Set Iteration = Sprint <N> (2-week iteration).
4. Confirm capacity and commit.

Sprint Backlog definition in GitHub:

• All items with Iteration = Sprint <N>.

---

4.3 Daily Standup

Where: Org Project “Current Sprint Board”

Focus filters:

• Status = Blocked
• Status = In Review (stuck PRs)
• Status = Ready to Release (release bottlenecks)

---

4.4 Sprint Review

Where: Org Project filtered by Iteration = Sprint <N>

• Demo items that reached Done (Released).
• Review items in Ready to Release and decide whether to release immediately or carry over.

---

4.5 Retro

Create Issues in a lightweight internal/process repo (optional), add to the same Org Project so improvement work competes fairly for capacity.

---

5) Pull Requests (Engineering Execution)

Rules

• Every PR must link to an Issue.
• Use Closes #<issue-id> in the PR description to connect work and automatically close issues on merge.
• Protect default branch (main) with required checks and review approvals.

Important note for your “Done = Released” policy

• Merging a PR should move the Project item to Ready to Release, not Done.
• Done happens only after the release is cut and deployed/available.

---

6) Releases (Per Repo, Independent)

Each repo releases independently:

• Tag version (SemVer recommended, e.g., v1.6.0)
• Create a GitHub Release with:
  • user-visible changes
  • migration notes
  • breaking changes
  • operational notes

Release → Done flow

• When a release containing the change is published (and deployed/available), the related Project items move to Done (Released).

---

7) Automation (Recommended Minimum)

Automation keeps the Org Project trustworthy without manual dragging.

Minimum automations

• New issue created in any repo → auto-add to Org Project
• PR opened → set Status = In Review
• PR merged → set Status = Ready to Release
• Release published (or deployment completed) → set Status = Done (Released)

---

8) Your Concrete Examples (How the process looks end-to-end)

Replace placeholder IDs with real Issue/PR numbers once created.

8.1 Example A — New Feature: “Questionnaire module” (Repo: gateway)

Step 1 — PO creates Issue

• Repo: gateway
• Issue: gateway#101 — Questionnaire module
• Fields in Org Project:
  • Repo = gateway
  • Priority = P1 (example)
  • Estimate = 8 (example)
  • Status = Backlog → refined to Ready

Step 2 — Sprint planning

• Set Iteration = Sprint 12 (example)
• Status = Ready

Step 3 — Development

• Developer sets Status = In Progress
• PR opened:
  • gateway#202 — “Implement questionnaire module”
  • PR includes Closes #101
• Status becomes In Review

Step 4 — Merge

• PR merged
• Status becomes Ready to Release

Step 5 — Release

• Tag: gateway v1.9.0 (example)
• GitHub Release notes mention gateway#101
• After deploy/availability:
  • Status becomes Done (Released)

---

8.2 Example B — New Feature: “Waterfall chart” (Repo: accelerator)

Step 1 — PO creates Issue

• Repo: accelerator
• Issue: accelerator#55 — Waterfall chart
• Fields in Org Project:
  • Repo = accelerator
  • Priority = P2 (example)
  • Estimate = 5 (example)
  • Status = Backlog → refined to Ready

Step 2 — Sprint planning

• Set Iteration = Sprint 12 (example)
• Status Ready

Step 3 — Development & Review

• PR: accelerator#80 — “Add waterfall chart component”
• PR includes Closes #55
• Status In Review

Step 4 — Merge → Ready to Release

• Merge PR
• Status Ready to Release

Step 5 — Release → Done (Released)

• Release: accelerator v2.3.0 (example)
• After deploy:
  • Mark accelerator#55 as Done (Released) in Org Project

---

9) Ready-to-paste Templates (Issue + PR)

The following are ready to paste into each repo. If you want them shared org-wide, create an org .github repository and place the templates there.

---

9.1 Issue Template (Issue Form) — Story / Feature

File path (in each repo): .github/ISSUE_TEMPLATE/story.yml Notes

• This form adds type:feature. If you prefer Project fields over labels, remove the label and rely on Project Type.
• A similar bug.yml following the format of story.yml.

name: "Story"
description: "Concise user story / feature with testable acceptance criteria"
title: "[Story] "
labels: ["type:feature"]
body:
- type: dropdown
  id: repo
  attributes:
    label: Repo / Service
    options:
      - gateway
      - accelerator
      - ai-case-completion
  validations:
    required: true

- type: dropdown
  id: priority
  attributes:
    label: Priority
    options: [P0, P1, P2]
  validations:
    required: true

- type: textarea
  id: what_why
  attributes:
    label: What / Why
    description: "What are we doing and why does it matter? (1–3 sentences)"
    placeholder: "Add a questionnaire module so users can fill and submit questionnaires in gateway."
  validations:
    required: true

- type: textarea
  id: acceptance
  attributes:
    label: Acceptance criteria
    description: "Use checkboxes; keep each item testable."
    placeholder: |-
      - [ ] ...
      - [ ] ...
  validations:
    required: true

- type: input
  id: estimate
  attributes:
    label: Estimate (points)
    placeholder: "3 / 5 / 8"
  validations:
    required: false

- type: textarea
  id: deps
  attributes:
    label: Dependencies / Links (optional)
    placeholder: |-
      - Depends on: <repo>#<id>
      - Design/doc: <url>
  validations:
    required: false

- type: textarea
  id: release_notes
  attributes:
    label: Release / rollout notes (optional)
    description: "Only if special handling is needed (flag, migration, config, rollback)."
    placeholder: |-
      Flag:
      Migration:
      Config:
      Rollback:
  validations:
    required: false

---

9.2 Pull Request Template

File path (in each repo): .github/pull_request_template.md

## Linked Issue
- Closes #<!-- issue-number -->

## What / Why
<!-- What change is being made, and why? -->

## Scope
- Included:
- Not included:

## How to Verify (PO-friendly)
<!-- Step-by-step verification. Include URLs if applicable. -->
1.
2.
3.

## Screenshots / Evidence (if applicable)
<!-- UI screenshots, logs, query results, etc. -->

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests / E2E (if applicable)
- [ ] Manual testing notes:

## Rollout / Release Notes
- Feature flag:
- Config changes:
- Migration:
- Backward compatibility:
- Rollback plan:

## Observability
- Metrics/logs/alerts added or updated:

## Checklist
- [ ] PR title is clear and follows repo conventions
- [ ] CI is green
- [ ] Required reviewers/CODEOWNERS approved
- [ ] Documentation updated (if needed)

---

10) One-screen Operating Checklist

Backlog / Refinement

• Every candidate item is an Issue in the right repo
• Added to Org Project
• Has Priority, Repo, Estimate, Acceptance criteria
• Moved to Ready

Sprint planning (2 weeks)

• Set Iteration = Sprint N for committed items
• Confirm scope and dependencies

Execution

• Dev moves item to In Progress
• PR links Issue (Closes #ID)
• PR merged → item becomes Ready to Release

Release

• Tag + GitHub Release created per repo
• Deploy/available confirmed
• Mark items Done (Released)

---

11) Notes / Decisions (Team-owned)

• Sprint length is 2 weeks.
• Repos: gateway, accelerator, ai-case-completion.
• “Done” means released, so we use Ready to Release to avoid counting “merged” as “done”.